@dinoxx/dinox-cli 1.0.22 → 1.1.0

package/README.md

@@ -52,7 +52,7 @@ Dinox CLI 适合这几类场景：
 
 安装前请先确认：
 
-- 已安装 Node.js 20 或更高版本
+- 推荐使用 Node.js 24 LTS；支持 Node.js 20.18.1+、22、23、24、25（不支持 Node.js 21 或 26+）
 - 已安装 npm
 - 你的系统可以正常执行全局 npm 命令
 
@@ -114,13 +114,15 @@ dino update
 ### 第 1 步：登录
 
 ```bash
-dino auth login "<你的 token>"
+read -rs DINOX_TOKEN
+printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
+unset DINOX_TOKEN
 ```
 
 说明：
 
-- 这里填的是登录 token 本体
-- `dino auth login` 建议传 token 本体，不要加 `Bearer ` 前缀
+- 第一行会在当前终端隐藏输入 token，避免 token 出现在命令参数和 shell 历史中
+- `--token-stdin` 接受 token 本体或 `Bearer ...`
 - 登录时 CLI 会顺便验证连接是否可用
 - 自动化或 CI 可以改用 `DINOX_TOKEN` 环境变量注入 token；它优先于本地配置，并支持 token 本体或 `Bearer ...`
 
@@ -452,7 +454,7 @@ dino note content-read <note-id> --format json
 dino note patch <note-id> --append-section "复盘" --content @./section.md --read-token <token> --format json
 ```
 
-`note patch` 只用于正文结构化编辑。真实写入前必须先 `content-read`，并传回 `readToken`；替换媒体、表格、未知节点等受保护 block 时，还需要显式 `--allow-protected-replace`。
+`note patch` 只用于正文结构化编辑。真实写入前必须先 `content-read`，并传回 `readToken`；token 短期有效（当前为 30 分钟，以 `readTokenExpiresAt` 为准），绑定生成它时当前账号对应的本地 PowerSync 数据库作用域，不能在切换账号或本地数据库后复用。token 也是单次使用的，任何真实 patch 尝试都会先消费它，失败后重试必须重新执行 `content-read`。替换媒体、表格、未知节点等受保护 block 时，还需要显式 `--allow-protected-replace`。
 
 #### 收藏状态
 
@@ -527,6 +529,7 @@ dino todo append --note-id <note-id> --tasks @./todo.txt
 
 ```bash
 dino todo update <task-id> --status completed
+dino todo update <task-id> --note-id <note-id> --status completed
 dino todo update <task-id> --status uncompleted
 ```
 
@@ -542,6 +545,8 @@ dino todo update <task-id> --status false
 - `completed`
 - `uncompleted`
 
+对没有持久 task id 的旧笔记，`todo search` 会返回 `legacy-task-*` 合成 id。该 id 绑定搜索时的任务位置和内容；如果笔记结构随后变化，更新会安全失败，必须重新搜索，避免把状态写到另一条任务。建议始终把搜索结果中的 `note_id` 一并传给 `--note-id`。
+
 ### 5.7 管理标签
 
 #### 查看全部标签
@@ -655,7 +660,9 @@ dino note search "AI" --offline --format json
 ### 6.2 `auth`：登录与状态
 
 ```bash
-dino auth login "<token>"
+read -rs DINOX_TOKEN
+printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
+unset DINOX_TOKEN
 dino auth status
 dino auth logout
 dino auth logout --clear-local-db
@@ -667,6 +674,8 @@ dino auth logout --clear-local-db
 - `status`：查看登录状态、本地库位置、同步状态
 - `logout`：退出登录
 - `logout --clear-local-db`：退出并删除本地 SQLite 缓存
+- logout 会优先清除配置中保存的凭据；若 daemon 停止、身份解析、数据库 owner lease 获取或释放、缓存删除失败，错误详情会返回 `persistedCredentialsCleared`、`cleanupPhase` 和缓存路径。CLI 会尝试释放全部已取得的 lease；即使某个 release 失败，也不会跳过后续 release 或覆盖更早的主错误。此时凭据已清，但不能认为本地清理已安全完成。
+- 当前 shell 中的 `DINOX_TOKEN` 不受 logout 影响；结果中的 `environmentTokenActive: true` 表示该环境仍可认证。
 
 ### 6.3 `sync`：手动同步
 
@@ -755,6 +764,7 @@ dino todo update <task-id> --status completed
   - `--dry-run`
 - `todo update`
   - `--status <status>` 必填
+  - `--note-id <id>`：用搜索结果中的笔记 id 精确限定目标
   - `--dry-run`
 
 ### 6.6 `tag`：标签管理
@@ -806,8 +816,9 @@ dino graph stats
 说明：
 
 - 这些命令用于查看笔记之间的链接关系
-- 在线模式下，CLI 会自动确保 daemon 可用
+- 在线模式下，CLI 会自动确保 daemon 可用，并通过 daemon-owned DB runtime 执行
 - 如果你只想用本地缓存而不启动 daemon，可加 `--offline`
+- 如果 daemon 不可用，默认在线模式会返回带 `suggested_action` 的结构化错误；不会静默回退到另一个进程打开本地 DB
 
 例如：
 
@@ -835,6 +846,7 @@ dino storage test
 dino storage test --storage-id <id>
 dino storage upload ./report.pdf
 dino storage upload ./photo.jpg --category images
+dino storage upload ./report.pdf --key imports/report.pdf --overwrite
 dino storage stats
 ```
 
@@ -846,7 +858,9 @@ dino storage stats
 - `storage upload` 会上传本地文件，并写入资源记录
 - 如果不是上传到当前活动存储，可用 `--storage-id <id>` 指定目标
 - `--category` 支持：`images`、`audios`、`files`、`videos`
-- 如果你想自己指定对象 key，可用 `--key <string>`
+- 如果你想自己指定对象 key，可用 `--key <string>`；key 和存储路径前缀不能包含纯 `.` 或 `..` 路径段，否则标准 URL 客户端会把路径归一化到错误对象
+- 显式 `--key` 默认拒绝覆盖已有主对象或图片缩略图；只有在确认替换这些精确 key 后才使用 `--overwrite`
+- 使用 `--overwrite` 时，一旦远端对象写入成功，后续缩略图或资源 metadata 记录失败不会自动删除已经写入的远端对象。不要把命令失败理解为远端已回滚；请检查结构化错误详情中的 `remoteObjectChanged`、`affectedKeys` 和主对象 `storageKey`，再核查或重试相关 key
 - `--dry-run` 非常适合在正式上传前确认目标位置
 
 ### 6.13 `schema`：查看命令 schema
@@ -884,6 +898,10 @@ dino daemon start --no-detach
 dino schema daemon.start --format json
 ```
 
+daemon 通过用户数据目录下的私有 Unix domain socket 通信，Windows 使用命名管道；`--port` 仅保留给旧脚本作为兼容字段，不再作为监听地址。
+
+需要在当前进程打开 PowerSync SQLite 的命令（例如写命令、`sync`、在线 `auth status`、`--offline` 或 `--require-sync` 读取）会先取得跨进程生命周期锁。如果同一用户数据库正由健康 daemon 持有，CLI 会暂时停止该实例；只有在命令结束、数据库关闭且 owner lease 成功释放后，才会按原端口恢复它。使用其他用户数据库的 daemon 不会被停止；如果关闭或释放失败，CLI 会保留 daemon 为停止状态并在 stderr 报告警告，避免两个运行时同时持有同一 SQLite 数据库。
+
 ### 6.15 `info`：查看版本与技能仓库地址
 
 ```bash
@@ -935,7 +953,9 @@ schema 包含命令路径、风险级别、参数、选项、输出字段和示
 解决：
 
 ```bash
-dino auth login "<token>"
+read -rs DINOX_TOKEN
+printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
+unset DINOX_TOKEN
 dino sync
 ```
 

package/dist/auth/userInfo.d.ts

@@ -5,6 +5,8 @@ export type AuthIdentity = {
     email: string | null;
     syncedAt: string;
 };
+export declare function persistedAuthStateMatches(left: DinoxConfig, right: DinoxConfig): boolean;
+export declare function rotatePersistedAuthStateRevision(config: DinoxConfig): DinoxConfig;
 export declare function buildPendingAuthConfig(rawConfig: DinoxConfig, authorization: string): DinoxConfig;
 export declare function mergeAuthIdentityIntoConfig(rawConfig: DinoxConfig, authorization: string, identity: AuthIdentity): DinoxConfig;
 export declare function fetchUserInfoWithAuthorization(input: {

package/dist/auth/userInfo.js

@@ -1,8 +1,22 @@
-import { saveConfig } from '../config/store.js';
+import { isDeepStrictEqual } from 'node:util';
+import { updateConfig } from '../config/store.js';
 import { DinoxError } from '../utils/errors.js';
 import { createTimeoutSignal, mergeAbortSignals } from '../utils/abort.js';
-import { toAuthorizationHeaderValue } from '../utils/authToken.js';
+import { normalizeAuthToken, toAuthorizationHeaderValue } from '../utils/authToken.js';
+import { generateId } from '../utils/id.js';
 const AUTH_CODE_OK = '000000';
+export function persistedAuthStateMatches(left, right) {
+    return isDeepStrictEqual(left.auth ?? {}, right.auth ?? {});
+}
+export function rotatePersistedAuthStateRevision(config) {
+    return {
+        ...config,
+        auth: {
+            ...(config.auth ?? {}),
+            stateRevision: generateId(),
+        },
+    };
+}
 export function buildPendingAuthConfig(rawConfig, authorization) {
     return {
         ...rawConfig,
@@ -73,9 +87,9 @@ function parseIdentity(payload) {
     };
 }
 function resolveUserInfoEndpoint(config) {
-    const base = normalizeOptionalString(config.powersync.uploadBaseUrl) ?? normalizeOptionalString(config.powersync.tokenEndpoint);
+    const base = normalizeOptionalString(config.powersync.tokenEndpoint);
     if (!base) {
-        throw new DinoxError('Missing backend base URL for user info');
+        throw new DinoxError('Missing PowerSync token endpoint for user info');
     }
     try {
         const url = new URL('/auth/userInfo', base);
@@ -96,9 +110,8 @@ export async function fetchUserInfoWithAuthorization(input) {
         ? createTimeoutSignal(effectiveTimeoutMs)
         : null;
     const requestSignal = mergeAbortSignals([input.signal, timeout?.signal]);
-    let response;
     try {
-        response = await fetch(endpoint, {
+        const response = await fetch(endpoint, {
             method: 'GET',
             headers: {
                 Authorization: toAuthorizationHeaderValue(authorization),
@@ -106,6 +119,28 @@ export async function fetchUserInfoWithAuthorization(input) {
             },
             signal: requestSignal,
         });
+        if (!response.ok) {
+            let body = '';
+            try {
+                body = await response.text();
+            }
+            catch (error) {
+                if (requestSignal?.aborted) {
+                    throw error;
+                }
+            }
+            throw new DinoxError(`User info request failed (${response.status}): ${body || endpoint}`);
+        }
+        let payload = null;
+        try {
+            payload = await response.json();
+        }
+        catch (error) {
+            if (requestSignal?.aborted) {
+                throw error;
+            }
+        }
+        return parseIdentity(payload);
     }
     catch (error) {
         if (timeout?.signal.aborted && !input.signal?.aborted) {
@@ -116,12 +151,6 @@ export async function fetchUserInfoWithAuthorization(input) {
     finally {
         timeout?.cancel();
     }
-    if (!response.ok) {
-        const body = await response.text().catch(() => '');
-        throw new DinoxError(`User info request failed (${response.status}): ${body || endpoint}`);
-    }
-    const payload = await response.json().catch(() => null);
-    return parseIdentity(payload);
 }
 export async function refreshAndPersistAuthIdentity(rawConfig, resolvedConfig) {
     const authorization = normalizeOptionalString(resolvedConfig.auth.authorization);
@@ -132,8 +161,20 @@ export async function refreshAndPersistAuthIdentity(rawConfig, resolvedConfig) {
         authorization,
         config: resolvedConfig,
     });
-    const nextConfig = mergeAuthIdentityIntoConfig(rawConfig, authorization, identity);
-    await saveConfig(nextConfig);
+    // Environment-only credentials are process-scoped and must never be copied into config.json.
+    if (normalizeAuthToken(rawConfig.auth?.authorization) !== authorization) {
+        return identity;
+    }
+    await updateConfig((current) => {
+        if (!persistedAuthStateMatches(current, rawConfig)) {
+            throw new DinoxError('Authentication changed while user identity was being refreshed.', {
+                code: 'AUTH_STATE_CHANGED',
+                suggestion: 'Retry the command so it uses the current login.',
+                recoverable: true,
+            });
+        }
+        return mergeAuthIdentityIntoConfig(current, authorization, identity);
+    }, { timeoutMs: resolvedConfig.sync.timeoutMs });
     return identity;
 }
 function authIdentityFromResolvedConfig(resolvedConfig) {

package/dist/cli.js

@@ -3,6 +3,7 @@ import { registerAuthCommands } from './commands/auth/index.js';
 import { registerBoxesCommand } from './commands/boxes/index.js';
 import { registerConfigCommands } from './commands/config/index.js';
 import { registerDaemonCommands } from './daemon/index.js';
+import { registerDoctorCommand } from './commands/doctor.js';
 import { registerGraphCommands } from './commands/graph/index.js';
 import { registerInfoCommand } from './commands/info/index.js';
 import { registerMetaCommands } from './commands/meta/index.js';
@@ -15,15 +16,47 @@ import { registerUpdateCommand } from './commands/update.js';
 import { registerTagsCommand } from './commands/tags/index.js';
 import { registerTodoCommands } from './commands/todo/index.js';
 import { getPackageVersion } from './utils/version.js';
-import { clearRequestedStructuredOutputFormat, resolveStructuredOutputFormat, setRequestedStructuredOutputFormat, } from './utils/output.js';
+import { buildStructuredErrorPayload, DinoxError } from './utils/errors.js';
+import { clearRequestedStructuredOutputFormat, parseStructuredOutputFormatFromArgv, printError, resolveStructuredOutputFormat, setRequestedStructuredOutputFormat, } from './utils/output.js';
 export function createCli() {
     clearRequestedStructuredOutputFormat();
     const program = new Command();
+    let structuredCommanderErrorWritten = false;
     program
         .name('dino')
         .description('Dinox CLI')
         .version(getPackageVersion())
-        .showHelpAfterError();
+        .showHelpAfterError()
+        .configureOutput({
+        writeErr: (text) => {
+            if (!structuredCommanderErrorWritten) {
+                process.stderr.write(text);
+            }
+        },
+        outputError: (text, write) => {
+            let format = null;
+            try {
+                const rawArgs = program.rawArgs ?? process.argv;
+                format = parseStructuredOutputFormatFromArgv(rawArgs.slice(2));
+            }
+            catch {
+                write(text);
+                return;
+            }
+            if (!format) {
+                write(text);
+                return;
+            }
+            structuredCommanderErrorWritten = true;
+            const message = text.trim().replace(/^error:\s*/i, '');
+            const error = new DinoxError(message, {
+                code: 'USAGE_ERROR',
+                recoverable: true,
+            });
+            printError(buildStructuredErrorPayload(error, false), format);
+        },
+    })
+        .exitOverride();
     program
         .option('--json', 'legacy machine-readable YAML output (equivalent to --format yaml)')
         .option('--format <format>', 'structured output format: yaml | json')
@@ -42,6 +75,7 @@ export function createCli() {
     registerBoxesCommand(program);
     registerConfigCommands(program);
     registerDaemonCommands(program);
+    registerDoctorCommand(program);
     registerGraphCommands(program);
     registerInfoCommand(program);
     registerMetaCommands(program);

package/dist/commands/auth/index.d.ts

@@ -1,4 +1,39 @@
 import { Command } from 'commander';
+import { fetchUserInfoWithAuthorization } from '../../auth/userInfo.js';
+import { loadConfig, updateConfig } from '../../config/store.js';
+import { resolveConfig } from '../../config/resolve.js';
+import { restoreSuspendedDaemonLocked, suspendDaemonForExclusiveAccessLocked } from '../../daemon/lifecycle.js';
+import { acquireDaemonStartLock } from '../../daemon/pid.js';
+import { fetchCredentialsWithAuthorization } from '../../powersync/connector.js';
+import { closePowerSyncAndReleaseOwner, connectPowerSync, getStatusSnapshot } from '../../powersync/runtime.js';
+import { runSingleSyncPass } from '../../powersync/syncPass.js';
 import type { CommandGroupDescriptor } from '../descriptor/types.js';
+import { printHumanReadableWarning } from '../../utils/output.js';
+export declare function releaseOwnerLeases(releases: ReadonlyArray<() => Promise<void>>): Promise<unknown[]>;
+type AuthLoginDependencies = {
+    acquireDaemonStartLock: typeof acquireDaemonStartLock;
+    loadConfig: typeof loadConfig;
+    resolveConfig: typeof resolveConfig;
+    fetchCredentials: typeof fetchCredentialsWithAuthorization;
+    fetchUserInfo: typeof fetchUserInfoWithAuthorization;
+    suspendDaemon: typeof suspendDaemonForExclusiveAccessLocked;
+    connectPowerSync: typeof connectPowerSync;
+    runSingleSyncPass: typeof runSingleSyncPass;
+    getStatusSnapshot: typeof getStatusSnapshot;
+    closePowerSyncAndReleaseOwner: typeof closePowerSyncAndReleaseOwner;
+    updateConfig: typeof updateConfig;
+    restoreDaemon: typeof restoreSuspendedDaemonLocked;
+    printWarning: typeof printHumanReadableWarning;
+};
+export declare function performAuthLogin(rawToken: string, syncTimeout: unknown, overrides?: Partial<AuthLoginDependencies>): Promise<{
+    ok: true;
+    verified: true;
+    endpoint: string;
+    dbPath: string;
+    stale: boolean;
+    lastSyncedAt: string | null;
+    userId: string;
+}>;
 export declare const authCommandGroup: CommandGroupDescriptor;
 export declare function registerAuthCommands(program: Command): void;
+export {};